package cn.iocoder.yudao.module.system.service.examscore;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.system.controller.admin.examscore.vo.*;
import cn.iocoder.yudao.module.system.dal.dataobject.examscore.ExamScoreDO;
import org.springframework.web.multipart.MultipartFile;

import javax.validation.Valid;
import java.io.IOException;
import java.util.Collection;
import java.util.List;

/**
 * 学生成绩 Service 接口
 *
 * @author 芋道源码
 */
public interface ExamScoreService {

    /**
     * 创建学生成绩
     *
     * @param createReqVO 创建信息
     * @return 编号
     */
    Long createExamScore(@Valid ExamScoreCreateReqVO createReqVO);

    /**
     * 更新学生成绩
     *
     * @param updateReqVO 更新信息
     */
    void updateExamScore(@Valid ExamScoreUpdateReqVO updateReqVO);

    /**
     * 删除学生成绩
     *
     * @param id 编号
     */
    void deleteExamScore(Long id);

    /**
     * 清除某次导入的所有成绩数据
     *
     * @param examId 考试ID
     * @return 删除的记录数
     */
    int deleteExamScoresByExamId(Long examId);
    
    /**
     * 根据导入批次ID删除成绩数据
     *
     * @param importBatchId 导入批次ID
     * @return 删除的记录数
     */
    int deleteExamScoresByImportBatchId(String importBatchId);
    
    /**
     * 根据导入批次ID查询成绩数量
     *
     * @param importBatchId 导入批次ID
     * @return 成绩数量
     */
    Long getScoreCountByImportBatchId(String importBatchId);

    /**
     * 获得学生成绩
     *
     * @param id 编号
     * @return 学生成绩
     */
    ExamScoreDO getExamScore(Long id);

    /**
     * 获得学生成绩列表
     *
     * @param ids 编号
     * @return 学生成绩列表
     */
    List<ExamScoreDO> getExamScoreList(Collection<Long> ids);

    /**
     * 获得学生成绩分页
     *
     * @param pageReqVO 分页查询
     * @return 学生成绩分页
     */
    PageResult<ExamScoreDO> getExamScorePage(ExamScorePageReqVO pageReqVO);

    /**
     * 获得学生成绩列表, 用于 Excel 导出
     *
     * @param exportReqVO 查询条件
     * @return 学生成绩列表
     */
    List<ExamScoreDO> getExamScoreList(ExamScorePageReqVO exportReqVO);

    /**
     * 根据考试ID获取成绩列表
     *
     * @param examId 考试ID
     * @return 成绩列表
     */
    List<ExamScoreDO> getExamScoreListByExamId(Long examId);

    /**
     * 根据学生ID获取成绩列表
     *
     * @param studentId 学生ID
     * @return 成绩列表
     */
    List<ExamScoreDO> getExamScoreListByStudentId(Long studentId);

    /**
     * 根据考试ID和学生ID获取成绩
     *
     * @param examId 考试ID
     * @param studentId 学生ID
     * @return 学生成绩
     */
    ExamScoreDO getExamScoreByExamIdAndStudentId(Long examId, Long studentId);

    /**
     * 批量导入成绩
     *
     * @param examId 考试ID
     * @param file Excel文件
     * @return 导入结果
     * @throws IOException IO异常
     */
    ExamScoreImportRespVO importScores(Long examId, MultipartFile file) throws IOException;

    /**
     * 新高考成绩批量导入（自动创建考试）
     * 从Excel第一行解析考试信息并自动创建考试，支持新高考格式
     *
     * @param file Excel文件
     * @return 导入结果
     * @throws IOException IO异常
     */
    ExamScoreImportRespVO importNewExamScores(MultipartFile file) throws IOException;

    /**
     * 获取成绩导入模板
     *
     * @return 模板数据
     */
    List<ExamScoreImportExcelVO> getImportTemplate();

    /**
     * 获取支持的模板数据源类型
     *
     * @return 数据源类型列表
     */
    List<String> getSupportedTemplateSourceTypes();

    /**
     * 检查模板数据源类型是否支持
     *
     * @param sourceType 数据源类型
     * @return 是否支持
     */
    boolean isTemplateSourceTypeSupported(String sourceType);

    /**
     * 计算排名
     *
     * @param examId 考试ID
     */
    void calculateRanking(Long examId);

    /**
     * 获取考试成绩统计信息
     *
     * @param examId 考试ID
     * @return 统计信息
     */
    ExamScoreStatisticsRespVO getExamScoreStatistics(Long examId);

    /**
     * 获取成绩分析报告
     *
     * @param examId 考试ID
     * @return 分析报告
     */
    ExamScoreAnalysisRespVO getExamScoreAnalysis(Long examId);

    /**
     * 获取等效分导出数据列表
     * 根据学生的总分赋分计算2024和2025年的等效分和等效位次
     *
     * @param examId 考试ID
     * @return 等效分导出数据列表
     */
    List<ExamScoreEquivalentExportVO> getEquivalentScoreExportList(Long examId);

}